docs: correct the certification guides against current libraries - #408

…x broken examples (#407)

The `certified-variables` skill is brought up to date with
[`@dfinity/certificate-verification`
4.0.0](https://www.npmjs.com/package/@dfinity/certificate-verification/v/4.0.0),
which peers `@icp-sdk/core` ^6, and with the current Rust and Motoko
libraries. Every code block was compiled, deployed to a local network
(icp-cli 1.5.0) and exercised end to end, and several were broken on
`main`.

**Broken on `main`, now fixed:**
- **Frontend verification did not type-check** against
certificate-verification 4 / core 6. The parameters are now
`Uint8Array`, not `ArrayBuffer`. `lookup_path` returns a `LookupResult`,
not bytes, so the old `if (!leafData)` check never fired. The new code
switches on `Found`/`Absent` and rejects `Unknown`. Treating `Unknown`
as absent would let a replica hide a real value behind a witness for a
different key (new pitfall 6). The helpers also accept
`@icp-sdk/bindgen`'s output as returned, where an empty `opt` field is
`undefined`, not `null`.
- **The Motoko `CertTree` example did not compile.** `let ct =
CertTree.Ops(...)` fails with `M0131` in a persistent actor and needs
`transient`. The deprecated `postupgrade` hook is dropped.
- **The Rust example failed `icp deploy`.** It lacked
`ic_cdk::export_candid!()`, so the Rust recipe failed with
`get_candid_pointer`.
- **Every `icp canister call … get` was wrong.** icp-cli sends an update
call unless `--query` is passed, so the Rust getter trapped and the
Motoko getters returned `certificate = null`.
- **The upgrade pitfall was wrong.** Certified data **survives**
upgrades (`abstract-behavior.md:2690-2693`, confirmed locally). What is
lost is a heap tree, so Rust must rebuild it and re-set the hash, while
Motoko's `CertTree.Store` needs nothing.
- **The HTTP certification snippet was incomplete.** It had no
`http_request` handler, no witness header, and no
`IC-CertificateExpression` header in the certified response. The last
one makes `ic-http-certification` 4 return
`CertificateExpressionHeaderMissing`. It is replaced by a complete
minimal canister, moved to `references/http-certification.md`.

**Restructured for agents.** The skill now opens with **"Who Verifies
What"**, which answers whether client-side verification is needed and
with which library:

| Response | Verified by |
|---|---|
| HTTP via `<id>.icp.net` or a custom domain | the gateway |
| HTTP via `raw` or your own client | nobody; use
`@dfinity/response-verification` |
| Update call through an actor | the agent |
| Candid query | only the answering node's signature; use certified data
plus `@dfinity/certificate-verification` |

The ICRC-3 tip certificate is covered as a use case.

The body shrinks from 482 to about 370 lines, and the size warning is
gone:
- Overlapping pitfalls are merged.
- The conceptual diagram is dropped.
- The deploy walkthrough and "Verify It Works" become a two-command
check.
- The HTTP material moves to a reference.

**Updated:**
- **Rust:** `ic-cdk` 0.20, `ic-certification` 4 (same `RbTree` API as
`ic-certified-map`, and what the official examples use),
`ic-http-certification` 4.
- **New no-witness frontend path** (`Certificate.create` +
`certified_data`) for the single-value Motoko example, linking
[`motoko/cert-var`](https://github.com/dfinity/examples/tree/master/motoko/cert-var).
- **Root key guidance** now follows the `ic_env` cookie, or `icp network
status --json` in Node, with the same serving-network caveat as #405.
- **Certified assets** point to the `static-site` skill instead.

<details>
<summary>Verification (local network)</summary>

| Check | Result |
|---|---|
| Rust KV (`ic-certification` 4 / `ic-cdk` 0.20), Motoko `CertTree` |
present → value; missing → proof of absence; tampered value → throws;
other key's witness → `Unknown`, throws |
| `@icp-sdk/bindgen` 0.4 actor passed straight to the helper (Motoko
`CertTree`) | present → value; absent key (`value` is `undefined`) →
`null`; tampered or dropped value → throws |
| Motoko single value, `verifySingleValue` | fresh install and after a
set both verify; tampered value throws |
| HTTP canister through the local gateway | `200 hello`, and a certified
`404` for other paths. A variant serving an uncertified body is rejected
with `backend_response_verification`; certifying without
`IC-CertificateExpression` returns `CertificateExpressionHeaderMissing`
|
| Upgrade without re-setting | Motoko single value still verifies; Rust
verifies with a proof of absence after `post_upgrade` |
| Local gateway, tampered response | rejected on `<id>.localhost`,
served on `<id>.raw.localhost` |
| Mainnet ckBTC ledger `icrc3_get_tip_certificate` |
`verifyCertification` passes; `last_block_index` and `last_block_hash`
are `Found` |

</details>

<details>
<summary>Eval results (new file, all cases with baseline, rerun on the
restructured skill)</summary>

- Case 1, "Adversarial: certified getter traps when called from
icp-cli": WITH 3/3 | WITHOUT 3/3. This is a regression guard for the
`--query` pitfall.
- Case 2, "Frontend witness verification with certificate-verification
4": WITH 4/4 (twice) | WITHOUT 3/4. The baseline returns null regardless
of lookup status; a later baseline run timed out.
- Case 3, "Adversarial: certified queries fail after a Rust canister
upgrade": WITH 3/3 (three runs) | WITHOUT 1/3, 2/3, 1/3. The baseline
claims certified data is reset on upgrade.
- Case 4 (new), "Adversarial: gateway assumed to verify Candid query
calls": WITH 3/3 (twice, the second after the gateway-proxy wording fix)
| WITHOUT 3/3. This is a regression guard for the decision table.
- Case 5, "Adversarial: CertTree declarations in a persistent Motoko
actor": WITH 3/3 (twice) | WITHOUT 2/3. The baseline insists on a
postupgrade hook.
- Case 6, "Adversarial: ic-http-certification header and fallback
errors": WITH 4/4 (three runs) | WITHOUT 4/4, 4/4, 3/4. This is a
regression guard for pitfall 9 and the certified 404.
- Case 7, "Adversarial: certify the initial value of a Motoko certified
variable": WITH 4/4 (twice) | WITHOUT 3/4 (twice). The baseline never
certifies the initial value.
- Case 8 (new), "Adversarial: bindgen returns an empty opt as
undefined": WITH 4/4 (twice) | WITHOUT: no result. The baseline produced
no code in either run (a permission request, then a timeout).
- Triggers: should-trigger 4/4, should-not-trigger 2/2.

</details>

Refs #406 (its `certified-variables` row: the `rootKey` type fix is done
here). The developer-docs guides with the same errors are fixed in
dfinity/developer-docs#408.